Power Programmierung 2

home *** CD-ROM | disk | FTP | other *** search

/ Power Programmierung 2 / Power-Programmierung CD 2 (Tewi)(1994).iso / gnu / djgpp / contrib / dvx / docs / dvapi.doc < prev next >

Wrap

Text File | 1993-07-15 | 14.7 KB | 575 lines

DESQview/X Systewm Library Programming Reference ------------------------------------------------ The following functions are system-level calls that compose the non-BSD portion of the DESQview/X System Library. General Functions: dvpath - get the directory into which DESQview/X has been installed. CanonicalPath - calls DOS int 21 function 60h. pmiSegAbsolute - return a DOS extender independent first meg address. pmiSegCancel - cancel a protected mode selector. apiBeginC - begin critical region. apiEndC - end critical region. apiIsObj - determine if a given handle is valid. apiPause - give other tasks a chance to run. Application Management Functions: NewProc - start a new process . pif_open - open a program information file, using the dvp search path. pif_start - starts a process, using a filename as argument. Window Management Functions: winMe - get the current tasks window handle. winStream - write a stream to a window. Mailbox Management Functions: malFind - find a mailbox by name. malName - assign a global name to a mailbox.. malSizeOf - get number of messages pending. malAddTo - send a message by value with given status. malFree - free a mailbox object. malNew - create a new mailbox. malOpen - open a mailbox. malNRead - read a mailbox. Object Management Functions: obqClose - close a tasks objectq . obqOpen - open the tasks objectq. obqSizeOf - get number of objectq entries pending. obqRead - wait for any object to have input. Timer Management Functions: timAddTo - start a timer for a given interval. timFree - free a timer object. timNew - create a timer object. General Functions ----------------- dvpath() - get the directory into which DESQview/X has been installed. SYNOPSIS -------- #include <qdeck.h> void dvpath(char *dvxdir); DESCRIPTION ----------- Returns the directory into which DESQview/X has been installed. dvxdir must be pre-allocated before dvpath is called. Canonical Path() - returns a canonical path SYNOPSIS -------- #include <qdeck.h> int CanonicalPath(char *inpath, char *outpath); DESCRIPTION ----------- Calls DOS interrupt 21 function 60h to return a canonical path. pmiSegAbsolute() - return a DOS extender independent real mode address SYNOPSIS -------- #include <pmi.h> char *pmiSegAbsolute(unsigned short seg, unsigned short offset, unsigned short len); DESCRIPTION ----------- This function returns a DOS extender independent real-mode address. For a 16-bit protected mode program this function creates a protected mode selector, with the segment limit set to 'len' bytes; a size of 0 represents 64K. For a 32-bit protected mode program this function maps an address to the first Megabyte selector. This function is necessary when copying data from protected mode to real mode. It should be used in conjunction with pmiSegCancel(); pmiSegCancel() - cancel a protected mode selector SYNOPSIS -------- #include <pmi.h> void pmiSegCancel(void farptr); DESCRIPTION ----------- This function cancels a protected mode pointer.The memory is not freed or released; the selector is merely made invalid. apiBeginC() - begin critical region SYNOPSIS -------- #include <dvapie.h> void apiBeginC(void); DESCRIPTION ----------- The apiBeginC function causes the current task to enter a critical region during which all multitasking is suspended. The calling task is allowed to continue execution until it calls apiEndc or voluntarily gives up control. If it voluntarily gives up control (by waiting for keyboard input for instance) multitasking is allowed to resume until the task regains control, at which time multitasking is again suspended. This facility can be useful for executing time critical sections of code and for controlling access to common resources. It should be used sparingly to avoid degrading overall system performance. If another task is using DOS when the apiBeginC call is made, the caller will be suspended until DOS is free. This means that you are free to call DOS from inside a critical region. apiEndC() - end critical region SYNOPSIS -------- #include <dvapie.h> void apiEndC(void); DESCRIPTION ----------- The apiEndC function defines the end of a critical region of code. Critical regions are entered via the apiBeginC function. Calls to apiBeginC and apiEndC may be nested. Multitasking does not resume until an apiEndC call has been executed for every apiBeginC call that has been made. apiIsObj() - determine if a given handle is valid SYNOPSIS -------- #include <dvapie.h> int apiIsObj(objhan); DESCRIPTION ----------- The apilsObj function returns 1 if the value specified is the handle of a currently valid object. Otherwise, it returns 0. It is generally better to keep track of your own objects rather than depend on this call. It can help, however, in error paths where bookkeeping can be difficult. apiPause() - give other tasks a chance to run SYNOPSIS -------- #include <dvapie.h> void apiPause(void); DESCRIPTION ----------- The apiPause function gives up control to the dispatcher so that other tasks can be run. The calling task will regain control when its normal turn occurs. Applications should make this call within all busy-wait loops, that is, loops that are doing nothing useful but looking for something to do. Application Management Functions --------------------------------- NewProc() - start a new process SYNOPSIS -------- #include <qdeck.h> unsigned long NewProc(char *dvpbuf,int len); DESCRIPTION ----------- Creates a new DESQview/X process. dvpbuf is a dvp either previous read from disk or one created in memory. len is the length of the dvp being passed in dvpbuf. Allows a task to start a new process, just as if the user had selected it from the window manager menu. dvpbuf is a dvp either previously read from disk or one created in memory. len is the length of the dvp being passed in dvpbuf. Return Value ------------ NewProc() returns the handle of the new process' initial task to the caller. pif_open() - open a program information file, using the dvp search path. SYNOPSIS -------- #include <qdeck.h> FILE *pif_open(char *pifname, char **pathname); DESCRIPTION ----------- Opens a dvp program information file, given a pathname. You may want to use pif_open in conjunction with fread() and NewProc() if adjustments need to be made to the dvp before it is started. Return Value ------------ Returns a file handle on success or NULL on failure. pif_start() - starts a process, using a filename as argument. SYNOPSIS -------- #include <qdeck.h> int pif_start(char *args); DESCRIPTION ----------- Starts a process, using a filename as argument. The first word of args must be a file name. If no extension is present a .dvp will be added. If no path is present the file will be looked for in current directory then in the path. Return Value ------------ Returns 0 on success, ENOENT if the file specified by args is not found, EBADF if the file specified by args is invalid, E2BIG if the dvp if the file specified by args is an invalid length and ENOEXEC if the new process cannot be started. Window Management Functions --------------------------- winMe() - get the current tasks window handle SYNOPSIS -------- #include <dvapie.h> unsigned long winMe(void); DESCRIPTION ----------- The winMe function returns the handle of the current task's window. winStream() - write a stream to a window SYNOPSIS -------- #include <dvapie.h> unsigned long winStream(unsigned long winhan, char * stream); DESCRIPTION ----------- The winStream function sends a data stream to a window. Returns a new window handle or 0, given a window handle and a pointer to a stream to be written. winStream cannot be used to define a field table entry Mailbox Management Functions ---------------------------- malFind - find a mailbox by name SYNOPSIS -------- #include <dvapie.h> unsigned long malfind (char *name, int lname); /* char *name; pointer to name string */ /* int lname; length of name string */ DESCRIPTION ----------- The malFind function searches for a mailbox with the given name and returns its handle, or zero if no mailbox has that name. malName() - assign a global name to a mailbox SYNOPSIS -------- #include <dvapie.h> void malName (unsigned long malhan,char *name,int lname); /* unsigned long malhan; mailbox handle */ /* char *name; pointer to name string */ /* int lname; length of name string */ DESCRIPTION ----------- The malName function assigns a name to a mailbox. Once a mailbox has been named, other tasks can determine its handle by calling the malFind function. malSizeOf() - get number of messages pending SYNOPSIS -------- #include <dvapie.h> int malSizeOf (unsigned long malhan); /* mailbox handle */ DESCRIPTION ----------- Returns the number of messages currently queued to the mailbox. malAddTo() - send a message with given status SYNOPSIS -------- #include <dvapie.h> int malAddto (unsigned long malhan,char *buffer, int buflen, int status, int append); /* unsigned long malhan; mailbox handle */ /* char *buffer; pointer to message */ /* int buflen; length of message */ /* int status; status of message */ /* int apend; whether to append messages or not */ DESCRIPTION ----------- The malAddto function sends a message by value and explicitly sets the message status. If append is TRUE, messages of the same status can be appended and read as a stream. The status value is supplied by the sender and is an arbitrary value in the range 0 to 255. Return Value ------------ Returns zero on success or non-zero on failure. malFree() - free a mailbox object SYNOPSIS -------- #include <dvapie.h> void malFree (unsigned long malhan); /* unsigned long malhan; mailbox handle */ DESCRIPTION ----------- The malFree function frees all memory associated with the mailbox including any messages still queued to the mailbox. malNew() - create a new mailbox SYNOPSIS -------- #include <dvapie.h> int malNew (unsigned long malhan); /* unsigned long malhan; mailbox handle */ DESCRIPTION ----------- The malNew function creates a new mailbox object and returns its handle. malOpen() - open a mailbox SYNOPSIS -------- #include <dvapie.h> void malOpen(unsigned long malhan); /* unsigned long malhan; mailbox handle */ DESCRIPTION ----------- The malOpen function opens a mailbox for input. It establishes the calling task as the owner of the mailbox and, therefore, as the only task allowed to read the mailbox. You must open a mailbox that you have created before any task can send messages to it. Your task mailbox is opened automatically for you by DESQview/X. malNRead() - read a mailbox SYNOPSIS -------- #include <dvapie.h> int malNRead(unsigned long malhan, car *name, int *len, int *stat); /* unsigned long malhan; mailbox handle */ /* char *name; pointer to mailbox name string*/ /* int *len; returns: pointer to length of message */ /* int *stat; returns: pointer to status value to associate with message */ DESCRIPTION ----------- The malNRead function returns the next message queued to the specified mailbox and its status. The length of the message is passed to the function with the requested length and returns the actual length read. When you read a mailbox that is not already open DESQview/X will open it for you. Return Value ------------ Returns zero on success and non-zero on failure. Object Management Functions --------------------------- obqClose() - close a tasks objectq SYNOPSIS -------- #include <dvapie.h> unsigned long obqClose(void); DESCRIPTION ----------- The obqClose function discards all objects from the task's objectq and prevents any further objects from being added. Each object in the objectq is erased to insure that its data is also discarded. The objects remain open. obqOpen() - open the tasks objectq SYNOPSIS -------- #include <dvapie.h> void obqOpen(void); DESCRIPTION ----------- The obqOpen function opens the task's objectq for use. obqSizeOf() - get number of objectq entries pending SYNOPSIS -------- #include <dvapie.h> int obqSizeOf (void); DESCRIPTION ----------- The obqSizeof function returns the number of objects in the calling task's objectq. obqRead() - wait for any object to have input SYNOPSIS -------- #include <dvapie.h> unsigned long obqRead (void); DESCRIPTION ----------- The obqRead function returns the object handle of the next object in the objectq. ObqRead of an empty objectq suspends the calling task until an object is added to the queue. The obqRead function automatically opens the objectq if it was not previously open. Timer Management Functions -------------------------- timAddTo() - start a timer for a given interval SYNOPSIS -------- #include <dvapie.h> void timAddto (unsigned long timhan,unsigned long interval); /* unsigned long timhan; timer handle */ /* unsigned long interval; # 1/100ths of a second in the time interval */ DESCRIPTION ----------- The timAddto function starts a timer running that will expire after a specified time interval. The duration of the timer is defined by a 32-bit number that represents the number of 1/100ths of a second in the interval. The timer is automatically opened if necessary. timFree() - free a timer object SYNOPSIS -------- #include <dvapie.h> void timFree (unsigned long timhan); /* unsigned long timhan; timer handle */ DESCRIPTION ----------- The timFree function closes a timer if it is still open and frees the memory associated with the timer object. timNew() - create a timer object SYNOPSIS -------- #include <dvapie.h> unsigned long timNew (unsigned long *timer); DESCRIPTION ----------- The timNew function creates a new timer object and returns its handle.